Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Binding and Unbinding Endpoints

OTBind

Assigns an address to an endpoint.

C INTERFACE

OSStatus OTBind(EndpointRef ref, TBind* reqAddr, TBind* retAddr);

C++ INTERFACES

OSStatus TEndpoint::Bind(TBind* reqAddr, TBind* retAddr);

PARAMETERS

ref

The endpoint reference of the endpoint that you are binding.

reqAddr

A pointer to a TBind structure (page 3-51) that contains information about the address to which you want to bind the endpoint and the number of possible outstanding connection requests if this is a connection-oriented endpoint.

If you specify NIL for the reqAddr parameter, Open Transport chooses a protocol address for you and requests 0 as the endpoint's maximum number of concurrent outstanding connect indications.

If you want Open Transport to assign an address for you, set the addr.len field of the TBind structure to 0.

retAddr

A pointer to a TBind structure (page 3-51) that, on return, indicates the address to which the endpoint is actually bound and, for connection-oriented endpoints, indicates the maximum number of concurrent outstanding connect indications that this endpoint actually allows. The TBind structure is described on page 3-51.

You can set this parameter to nil if you do not care to know what address the endpoint is bound to or what the negotiated value of qlen is.

DESCRIPTION

You call the OTBind function to request an address that an endpoint be bound to. You can either use the reqAddr parameter to request that the endpoint be bound to a specific address or allow the endpoint provider to assign an address dynamically by passing nil for this parameter. Consult the documentation for the top-level protocol you are using to determine whether it is preferable to have the address assigned dynamically. The function returns the address to which the endpoint is actually bound in the retAddr parameter. This might be different from the address you requested, if you requested a specific address.

If you are binding a connection-oriented endpoint, you must use the reqAddr->qlen field to specify the number of connection requests that may be outstanding for this endpoint. The retAddr->qlen field specifies, on return, the actual number of connection requests allowed for the endpoint. This number might be smaller than the number you requested. Note that when the endpoint is actually connected, the number might be further decreased by negotiations taking place at that time.

If you call the OTBind function asynchronously and you have not installed a notifier function, the only way to determine when the function completes is to poll the endpoint using the OTGetEndpointState function. This function returns a kOTStateChangeErr until the bind completes. When the endpoint is bound, the state is either T_UNBND if the bind failed, or T_IDLE if it succeeded.

You can cancel an asynchronous bind that is still in progress by calling the OTUnbind function.

You must not bind more than one connectionless endpoint to a single address. Some connection-oriented protocols let you bind two or more endpoints to the same address. In such instances, you must use only one of the endpoints to listen for connection requests for that address. When binding the endpoint listening for a connection, you must set the reqAddr->qlen field of the OTBind function to a value greater than or equal to 1. When binding the other endpoints, you must set the reqAddr->qlen field to 0.

If you accept a connection for an endpoint that is also listening for connection requests, the address of that endpoint is deemed "busy" for the duration of the connection, and you must not bind another endpoint for listening to that same address. This requirement prevents more than one endpoint bound to the same address from accepting connection requests. If you have to bind another listening endpoint to the same address, you must first use the OTUnbind function to unbind the first endpoint or use the OTCloseProvider function to close it.

SPECIAL CONSIDERATIONS

In asynchronous mode, the endpoint provider might call your notifier function before the function's initial return.

An endpoint may not allow an explicit binding of more than one endpoint to the same protocol address, although it allows more than one connection to be accepted for the same protocol address. To ensure portability, do not bind endpoints that are used as responding endpoints in a call to the OTAccept function, if the responding address is to be the same as the called address.

COMPLETION EVENT CODES

T_BINDCOMPLETE

0x20000001

The OTBind function has completed. The cookie parameter passed to the notifier function points to the retAddr parameter.

VALID STATES

All except T_UNINIT

SEE ALSO

To unbind an endpoint call the OTUnbind function (described next).

The TBind structure (page 3-51) is used to specify the address to which the endpoint is bound.

You use the OTCloseProvider function, described in the chapter "Providers" in this book, to close a provider.

For additional information about binding multiple connection-oriented endpoints to the same address, see "Processing Multiple Connection Requests," beginning on page 3-29, the OTConnect function (page 3-121), and the OTAccept function (page 3-127).

For information on how to use this function with a TCP/IP protocol, see page 8-16 in the TCP/IP chapter.

For information on how to use this function with AppleTalk protocols, see page 13-10 in the ADSP chapter, page 12-10 in the DDP chapter, and page 15-9 in the PAP chapter.